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Preface 


This booklet is an guide to the standard SunOS'^^ 4.0 system software doc¬ 
umentation set you receive with your Sun computer system. It is written for 
field support personnel, system administrators, users, and programmers. 
(This booklet does not describe the release-specific and platform-specific 
documentation.) 

It is divided into seven chapters and one appendix: 

1. Introducing Your Sun^^ System Software Documentation 

2. Beginner’s Guides 

3. Reference Manuals 

4. System and Network Administration Manuals 

5. Programmer’s Guides 

6. SPARC*"'^ Documents 

7. Organizing and Researching your Sun System Documents 
Appendix A contains a table of all manuals listed aphabetically. 
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Introducing Your Sun System 

Documents 


This chapter has the following objectives: 

□ To present some basic concepts in understanding and using the standard 
system documentation 

□ To describe in a general way the shipping containers and packaging of 
the manuals when they arrive at your site 

□ To introduce and prepare for the following chapters (2 through 7) 

Groups of Sun Xhe standard Sun software system documentation is organized into func- 

Software System tional groups of manuals. The groups of manuals and the chapters in which 


Documentation 

they are described are as follows: 



□ Beginner’s Guides 

Chapter 2 


□ Reference Manuals 

Chapter 3 


□ System Administration Manuals 

Chapter 4 


□ Programmer’s Guides 

Chapter 5 


□ SPARC Documents 

Chapter 6 


Sun System Users and x^e very generic term “user” can apply to different types or levels of users 

eir ocumentation including non-UNIX ^-specializing workstation users, network resource us¬ 

ers, programmers, and network and system administrators. All these are “us¬ 
ers” of the Sun system. In this document we try to specify the type of user. 
We do this so that you can identify your own needs with a particular cate¬ 
gory of documentation. 

A particular audience is targeted for each group of manuals, but complete 
segregation of the material is impossible. The knowledge of Sun system 
software required by the different users sometimes overlaps. For example, 
programmers and system administrators often use the same services that 
non-specializing users do and in addition, more specialized SunOS and Sun 
system software features. 


1. UNIX is a trademark of AT&T 
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2 Guide to Sun System Software Documentation 


The material covered in the above sequence of documentation groups is in 
ascending order of UNIX specialization. Figure 1-1 illustrates a concept of 
“users” based on degree and type of specialization in UNIX. 



#suti 

microsystems 


Revision A of 26 September 1989 









































1 — Introducing Your Sun System Software Etocuments 3 


Where to Start with 
Your Sun Software 
Documentation 


Figure 1-2 illustrates an exploration path to help route all users to the appro¬ 
priate documentation. This is the path recommended even for experienced 
users. Of course, if you are experienced you can go faster and skip the ma¬ 
terial you are already familiar with. 

Detailed example study plans for specific subjects are offered in Chapter 7, 
“Organizing and Researching Your Sun System Documents.” 


Figure 1-2 Basic Plan for Using Sun Software Documentation 
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4 Guide to Sun System Software Documentation 


How Sun Software 
Documentation 
Tracks SunOS 
Releases 


Read This First (RTF) 
Booklets 


Special Features of the 
Sun Software 
Documentation 


Using the Global Index 


Tables of Contents 


Using the Color-Coded 
Tab Dividers 


Much of the Sun software documentation is applicable to a particular release 
version of the SunOS. Some manuals are updated only with major release 
versions of the SunOS. For intermediate releases, important changes in the 
standard documentation are covered in the release-specific documentation 
and in special “late edition” documents titled Read This First. The major re¬ 
lease documentation must be interpreted in the light of the newer docu¬ 
ments. Sometimes this new information may supersede information in the 
standard documentation. 

As mentioned above. Read This First documents contain important late edi¬ 
tion information that was became available only after the main manuals 
were published. Usually RTFs are targeted to a specific release version of 
the SunOS and may have the release version named in their titles. RTFs can 
contain installation instructions, documentation errata, and additions to the 
manuals they pertain to. They can also contain bug fixes and notices of 
known problems with the software. 

There can be more than one RTF in a set of documentation. In fact, each 
manual or group of manuals can have its own RTF. 


Sun system software documentation makes use of some special features to 
facilitate organization and access of the information contained in it. Some 
of these features are highlighted in this section. They are listed as follows: 

□ Individual tables of contents 

□ Global Index 

□ Color-coded tab dividers 

□ Quick Reference Guides 

□ Sun binders 


Each book in the documentation set also contains its own index. In addition, 
a Global Index is included in the set of reference manuals. It contains entries 
that index subjects to all the books in the standard system software docu¬ 
mentation. The Global Index is especially useful because many subjects are 
covered in more than one manual. 


Each manual has a complete contents listing in the front of the manual. The 
contents provides a list of all chapter, section, and subsection heads, a list of 
tables, and a list of figures. In large manuals, each chapter has an individual 
contents pages at its beginning. 

Each manual has a tab cover with a large tab (3-1/2 inch) to separate it from 
the other manuals that may be included in the same binder. The larger man¬ 
uals have additional sets of 2-1/2 inch tabs for each major section. These 
tabs are lettered in bold caps. Some manuals, for example, the SunOS Ref- 
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Sun Binders 


Using Quick Reference 
Guides 


erence Manual, Editing Text Files, and Formatting Documents also have 
subsection tabs which are lettered in bold upper and lower case. 

Tabs are color-coded to further facilitate convenient access and organization 
of the manuals in your library. For example, The SunOS Reference Manual 
has gray tabs; while the Security Features Guide has red tabs. 

Probably the best way to keep you Sun system software documentation set 
is to put them in a set of Sun binders. This facilitates easy access and refer¬ 
ence. This suggestion is discussed further in the Chapter 7, “Organizing and 
Researching Your Sun System Documents.” 

There are three quick-reference guides and some other aids included loosely 
with your Sun software documentation set. The quick-reference guides are 
as follows: 

□ Getting Started with SunOS Quick Reference 

□ Doing More with SunOS Quick Reference 

□ Sun keycap adhesive labels 

“Getting Started with SunOS” Quick Reference provides handy explana¬ 
tions of commands such as: 

□ Your work session 

□ Manipulating files 

□ Using your calendar 

□ Editing files with vt 

□ Formatting your files with nroff 

□ Searching with grep 

“Doing More with SunOS” Quick Reference provides some of the more fre¬ 
quently used, but also more advanced commands for files, pipes, filters, his¬ 
tory substitution, and so forth. 

The Sun keycap adhesive labels can be applied to the keys of nonstandard 
keyboards. (For more information, see SunView 1 Beginner’s Guide, later 
in Chapter 2, “Beginner’s Guides.”) 
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6 Guide to Sun System Software Documentation 


Documentation 
Shipping Containers 
A and B 


The standard system software is contained in two rather large shipping con¬ 
tainers called A and B and one smaller box called the SPARC documenta¬ 
tion box. Figure 1-3 illustrates the three boxes. 


Figure 1-3 Sun System Software Documentation Shipping Containers 



sun 

microsystems 


Revision A of 26 September 1989 
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Shipping Container A: 
System Administration 
and Reference Manuals 


Figure 1-4 illustrates the contents of system shipping container A. When 
you open it, you notice that it contains two loose documents on top of the 
two smaller boxes. 


Figure 1-4 Software Shipping Container A and Contents 
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8 Guide to Sun System Software Documentation 


Shipping Container B: 
Beginner’s Guides and 
Programmer’s Guides 


Figure 1-5 illustrates the contents of the software shipping container B, 
which contains two smaller boxes: 

□ 4.0 Beginner’s Guides smaller box 

□ 4.0 Programmer’s Guides smaller box 


Figure 1-5 System Software Shipping Container B and Enclosed Boxes 



Smaller Boxes 


How the Following 
Chapters are 
Organized 


Shipping containers A and B each contain two smaller boxes. Figures 1-4 
and 1-5 illustrate shipping containers A and B and their contents. The small¬ 
er boxes contain a particular class of manuals of the library of standard 
SunOS and Sun system software documentation 

When you open a smaller box it is suggested that you: 

1. Notice a list of contents printed on card stock and an RTF. 

2. Check off the contents of the box against the list of contents. 

3. Read the RTF and file it at the front of the corresponding manual or 
group of manuals in your Sun 3-ring binders. 

In the following chapters, the contents of the smaller boxes are illustrated as 
icons. Each icon contains the part number of the manual, which you can use 
if you are missing a manual or if you wish to order additional copies. Each 
manual is described briefly following the illustration. 
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Sun System Introduction 


Beginners Guides 


Figure 2-1 illustrates the contents of the Beginner’s Guides box. This series 
of manuals are an excellent starting point for a non-UNIX-specialized user 
or even an intermediate or advanced user who is becoming acquainted with 
a Sun system features for the first time. Except for two bound as saddle- 
stitched booklets, the Beginner’s Guides series are perfect-bound books 
without tabs. 

The manuals are illustrated and described in a suggested order for reading 
and study. They are listed as follows: 

□ Sun System Introduction 

□ Getting Started with SunOS 

□ SunView™ 1 

□ Mail and Messages 

□ Using the network 

□ Setting Up Your SunOS Environment 

□ Doing More with SunOS 

□ Self Help with Problems 

This manual is a survey of much of the Sun hardware and software product 
line. It is not a “how to” tutorial but a get-acquainted guide to what is avail¬ 
able and where to find more information. It refers you to the appropriate 
manual for each subject covered. 

You would want to read this book if you are thinking about purchasing a Sun 
system, if you just acquired a Sun system, or if you are new to the Sun en¬ 
vironment. This might well be the first book you would want to read after 
your system is up and running and after you have read this Guide to Sun Sys¬ 
tem Software Documentation. Some of the areas the Sun System Introduc¬ 
tion covers are the following: 
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Figure 2-6 Contents of the Beginner’s Guides Box of Shipping Container B 



□ Sun product family 

□ SunOS and networking 

□ SunView window environment 


□ Logging on and off your system 

□ Using shells and files 

□ Editing and formatting text 

□ System administration 

□ Software development 

□ Graphics software 
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2 — Beginner’s Guides 11 


□ Unbundled and third party software 


Getting Started with SunOs This manual is an appropriately named guide to the basic tools you need to 

imm^iately begin using your workstation. It describes the keyboard, the 
terminal screen, mouse, the desktop windowing system. Sun View, the 
SunOS file system. It provides getting-started basic information and tutori¬ 
als for typing commands, editing, formatting, and searching files. It intro¬ 
duces timesaving features such as aliasing, on-line documentation (on-line 
Man Pages), a SunOS command summary, a glossary, and a bibliography. 
It also contains quick reference cards packed loose in the cover pages. The 
manual points you to more specialized Sun documentation for the subjects 
introduced. 


SunView 1 


Mail and Messages 


This manual is combination lesson tutorial and reference manual for Sun- 
View, the SunOS desktop windowing environment. SunView provides a set 
of workstation tools, such as the virtual terminal shell tool. These tools are 
introduced in the manual. The manual provides reading and study paths 
within it for both beginners and experienced window system users. 

This manual is devoted to the UNIX mail command and to the SunView 
Mail Tool, which is the SunOS intuitive user interface for UNIX mail. This 
manual also covers the interactive message programs talk and write. 

This very thorough manual is as much a reference manual as a beginner’s 
manual. It provides the basics and the more sophisticated aspects of using 
mail and Mail Tool, such as modifying your .mailrc file with the Defaults 
Editor and sending messages to recipients using uucp or the internetwork. 
Getting Started with SunOS and SunView 1 Beginner’s Guide are prerequi¬ 
sites for reading this manual. 


Using the Network 


This manual provides basic introductory information on using the network 
facilities available on your workstation. These include NFS^m and the Sun 
on-line network database service. It covers remote logins, remote command 
execution, and dialup access. The book provides a command summary and 
glossary. 


Setting Up Your SunOS 
Environment 


Doing More with SunOS 


This brief but powerful manual describes the setup files for the C shell com¬ 
mand interpreter and the interactive editor vi. The manual defines “environ¬ 
ment” as the various options and features that affect how the system or in¬ 
teractive program responds to you. It gives a sample set of files and provides 
the starting point for you to begin tailoring the system to your needs and 
style. 

This manual describes some of the more sophisticated features of the SunOS 
and how to use them to simplify complicated tasks. Some of the rich details 
provided are; 
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Self Help With Problems 


□ file attributes 

□ commands, pipes, and filters 

□ the C shell 

□ processes and concurrent tasks 

□ managing files 

□ printers, queues, and printing screen graphics 

The appendices provide reference material on C shell special characters. 
Bourne shell scripts, and a command summary. 

This manual describes how to avoid and what to do about problems that can 
arise during normal use of the SunOS system and some of its utilities. (It 
does not cover system maintenance and troubleshooting, which are found in 
System Network and Administration.) It covers problems with logging in 
and out. It describes error messages that can occur for selected commands, 
when editing text files, and when networking. 
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Reference Manuals 


Figure 3-1 illustrates the contents of the reference manuals box. This is a set 
of reference manuals for all types of users. The Reference manuals are listed 
as follows: 

□ System Services Overview 

□ SunOS Reference Manual 

□ Editing Text Files 

□ Using NROFF and TROFF 

□ Formatting Documents 

□ Global Index 

System Services Overview pink Tab. This manual is an introduction to the facilities provided by 

SunOS. It can serve as a tutorial for the novice user, as a review and sum¬ 
mary for an intermediate user of UNIX, and as a reference for UNIX spe¬ 
cialists learning the SunOS implementation. Here are some of the subjects 
covered: 

□ System and BSD compatibility of SunOS 

□ SunOS kernel interface and virtual machine facilities, file access, and 
virtual device controllers 

□ Networking, including socket-based interprocess communication and 
server-based network services 

□ Memory management 

□ Lightweight processes (threads) 


1. System V is a trademark of AT&T. 
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Figure 3-1 Reference Manuals Box of Shipping Container A 



un eference anual Gray Tabs. This is a very large manual (more than 1,8(X) pages). It contains 

the SunOS version of the Berkeley UNIX “Manual Pages.” Manual pages 
are alphabetically ordered sets of pages describing commands, functions, or 
other UNIX elements. (For more information on Man Pages, see Getting 
Started with SunOS: Beginner’s Guide.) Each Man Page description is 
structured with a standard format convention that consists of categories 
similar to the following: 

□ Name 

□ Synopsis (command syntax) 
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Reference Manuals 15 


Editing Text Files 


Using NROFF and 
TROFF 


□ Availability on Sun platforms 

□ Description 

□ Option 

□ Flags (if any) 

□ Usage 

□ Example 

□ Files 

□ Bugs 

□ See Also 

The manual is divided by numbered tabs into the sections as listed below. 
At the beginning of each section there is a alphabetical list of the elements 
contained in that section. 

1. User commands (alphabetically listed descriptions) 

2. System calls and error numbers 

3. User-level C library functions 

• Lightweight processes library (threads) 

• Mathematical library of functions and constants 

• RPC service library functions and protocols 

• System V functions library 

4. Devices, drivers, protocols and network interfaces 

5. File formats used or read by various programs 

6. Games and demos 

7. Public files, tables, and TROFF macros 

8. System maintenance and operations commands 

Light Green Tabs. The introduction of this manual offers a tutorial on us¬ 
ing the editors provided by SunOS. A chapter is devoted to each editor: v/, 
ex, ed, and sed. Other chapters cover searching, viewing, and comparing 
files. 

Dark Green Tabs. This manual is a tutorial and reference manual for 
NROFF and TROFF, the standard UNDC text formatting and type setting 
processors. TROFF works by reading dot-(.) commands and escape se¬ 
quences which you embed in your screen edit file. This manual divides the 
commands into functional and logical groups such as: line format, page lay¬ 
out, line spacing and character size, and so forth. The book also contains ap¬ 
pendices containing command summaries, number registers, and other ref¬ 
erence material. A full set of tabs helps to make this a handy reference book. 
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Formatting Documents 


Global Index 


Medium Green Tabs. This manual covers special formatting packages that 
work in conjunction with TROFF. Included are: families of text formatting 
macros, the indexing tool, refer, table formatting, equation setting, and ver¬ 
ification programs. A full set of tabs make this a handy reference book. 

White Tab. This manual is an extensive interbook index for the entire li¬ 
brary of Sun software documentation. It is essentially a two-column table 
with topical entries pointing to a “Where to Look” field consisting of the 
manual title and page number. It begins with a special character index and 
proceeds with the alphabetical entries. 
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System Administration Manuals 


Figure 4-1 illustrates the contents of the System administration manuals 
box. System Administration manuals, as you might expect from the title, are 
designed as reference and instruction manuals to aid system administrators 
perform their duties of installing, configuring, and maintaining a Sun sys¬ 
tem environment; however, sections of these manuals can be useful or are 
especially directed to users and programmers. 

The System Administration Manuals are listed as follows: 

□ SunOS 4.0 Changes Notes 

□ Installing the SunOS 

□ System and Network Administration 

□ S'^curity Features Guide 

□ PROM User’s Manual 

□ Sun System Diagnostics Manual 

SunOS 4.0 Change Notes Yellow Tabs. This manual is written for system administrators, program¬ 
mers, and users migrating from SunOS 3.x to 4.0. The manual reviews com¬ 
patibility, unbundled software availability, changes, and enhancements be¬ 
tween the release versions. For those beginning to use SunOS 4.0 and above, 
the manual may be helpful in highlighting current advances in SunOS. 


nstalhng the SunOS Yellow Tabs. This manual is the installation manual for SunOS 4.0 and is 

not needed to install SunOS 4.0.3 release. However it contains reference and 
background information that may be useful to all users in complementing 
knowledge contained in the current release and installation manuals and in 
learning installation concepts. Subjects include: SunInstalF“, directory 
structures, loading tapes, machine types, remote installations, installation 
for different platform configurations, and reconfiguring the kernel. 
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Fig\ire 4-1 System Administration Manuals Box of Shipping Container A 



System and Network Orange Tabs. This manual is a resource manual for learning and managing 

Administration Sun systems at SunOS 4.0 and higher. It provides procedures, explanations, 

terminology, tutorials, and information on disk maintenance, reconfiguring 
the kernel, adding hardware, and using the format utility. 

The networking chapters provide information on network administration, 
NFS^M, Sun on-line network database service, and electronic mail. The ref¬ 
erence part includes tutorials and explanations of advanced UNIX adminis¬ 
tration and networking subjects such as mail routing, printing configuration, 
termcap, uucp, and the name server. 


Security Features Guide Red Tabs. This manual is a comprehensive tutorial and guide to most as¬ 
pects of Sun system and network electronic security, from passwords to vi¬ 
ruses. It includes special sections for users, programmers, and administra¬ 
tors. 
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PROM User’s Manual 


Sun System Diagnostics 
Manual 


Brown Tabs. This manual describes the types of PROMs found in Sun sys¬ 
tems and what they do. Types of PROMs are boot, diagnostic, ID, and sys¬ 
tem configuration PROMs. A chapter is provided on Sun386FM self-tests 
and initialization. Hardware implementation PROMs are not covered in this 
manual. 

Brown Tab. This manual is a guide to the interactive Sun System Diagnos¬ 
tic test system, sysdiag. Running under SunOS, the program sysdiag tests 
memory, disk and tape drives, boards, and board-level devices. (This man¬ 
ual applies only to SunOS releases prior to 4.1. Releases from 4.1 upwards 
are shipped with Sundiag'^^. See the Sundiag User’s Guide shipped in the 
4.0.3 Release Box.) 
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Programmer’s Guides 


Figure 5-1 illustrates the contents of the Programmer’s Guides box. The 
Programmer’s Guides are listed in logical order as follows: 

□ C Programmer’s Guide 

□ Assembly Language Reference for Sun-2™ and Sun-3™ 

□ Debugging Tools 

□ Floating Point Programmer’s Guide 

□ Network Programming 

□ Programming Utilities and Libraries 

□ Writing Device Drivers 

□ SunView 1 Programmer’s Guide 

□ SunView 1 System Programmer’s Guide 

□ Pixrect™ Reference Manual 

□ Sun CGF^ Reference Manual 

□ SunCore™ Reference Manual 
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Figure 5-1 Contents of the Programmer’s Guides Box of Shipping Container B 



C Programmer's Guide Purple Tabs. This manual describes how to write C programs that interface 

with SunOS. Such programs include those that use files by name; that use 
pipes; that invoke commands as they run; or that catch interrupts and other 
signals during execution. Prerequisites are: 

□ Knowledge of C up to the level described in The C Programming 
Language, by Kemighan and Ritchie, Prentice-Hall, 1978 

□ Familiarity with SunOS as exemplified in SunOS Reference Manual 
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Assembly Language 
Reference for Sun-2 and 
Sun-3 


Debugging Tools 


Floating Point 
Programmer's Guide 


Although not definitive, this manual provides the basics on the following as¬ 
pects; 

□ Using the Sun C compiler 

□ Accessing a Program’s Environment 

□ Processes and signals 

□ Standard I/O, character I/O 

□ String and character handling 

Several appendices provide reference tables including Sun386i data repre¬ 
sentation. 

Purple Tabs. This manual describes syntax and usage of the assembler for 
some of the microprocessors used in Sun workstations and servers and 
Sun’s FPA. The basic format of the assembler is based on the DEC^ Macro- 
11 assembler, UNIX PDP-11^ assembler, and Motorola^ mnemonics and 
address format. 

Prerequisites are familiarity with the basics of assembly language and the 
relevant processors. 

Subjects covered are: 

□ Notation, elements of the assembly language, and expressions 

□ Assembly language program layout 

□ Assembler directives, instructions, and addressing modes 

Appendices document error codes, opcodes, and FPA Assembler Syntax. 

Purple Tabs. This manual describes three Sun debuggers: dfex, dbxtool, and 
adb. The manual is written for programmers experienced with C, assembler, 
FORTRAN, Modula-2 or Pascal. 

dbx is an interactive, line-oriented, source-level, symbolic debugger, dbx¬ 
tool is a window-based interface to dbx. adb is an interactive, line-oriented, 
assembly-level debugger. The first two are adequate for most debugging 
tasks. The latter is used for more advanced tasks, such as interactive exam¬ 
ination of binary files and debugging the kernel. Chapters on adb include tu¬ 
torials, a reference, debugging SunOS kernels, and generating scripts. 

Purple Tabs. This manual describes features of various Sun floating-point 
implementations, their use, options, numerics, performance, and conform¬ 
ance to IEEE standards. 


1. DEC and Macro-11 are trademarks of Digital Equipment Corporation 

2. PDP-11 is a trademark of Digital Equipment Corporation 

3. Motorola is a trademark of Motorola, Inc. 
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Network Programming 


Programming Utilities and 
Libraries 


Writing Device Drivers 


You should be familiar with the ANSI/IEEE standard, the Motorola FPA, or 
the Weitek^ chip set, according to your interests. This manual lists an exten¬ 
sive bibliography for further study. Numerous appendices provide reference 
material not easily obtainable elsewhere. 

Red Tabs. SunOS is structurally a network UNIX system that can adapt to 
changing network technology. Chapter 1 of this manual provides and exten¬ 
sive overview of the network services provided by SunOS, such as, NFS, 
pipes, sockets, network commands. Sun on-line network database service, 
and network managers and monitors. 

The chapters that follow are divided into three parts: 

□ Network programming using Remote Procedure Calls (RPC^“) and 
xdr2 

□ Protocol specifications for XDR, RPC, and NFS 

□ Socket-based Interprocess Communications (SunlPC^"^) 

Orange Tabs. This manual, written primarily for applications program¬ 
mers, provides an overview of SunOS programming environment and de¬ 
scribes system facilities, utilities, and libraries supported by that environ¬ 
ment. The manual is largely derived from BSD documents. 

The manual is organized into groups of chapters describing the following 
topics: 

□ System interface and support facilities for C programming 

□ C programming aids to check for correctness and to monitor 
performance 

□ System utilities for version control and compilation 

□ Program generation tools 

□ BSD and System curses terminal-display library routines 

Appendices describe low-level commands for SCCS and enhancements to 
the make utility. 

Dark Blue Tabs. This manual is a guide to adding drivers for new hardware 
devices to the SunOS kernel. The manual is divided into three parts: 

□ Regular device drivers (non-STREAMS) 


1. Weitek is a trademark of Weitek Corp. 

2. XDR is a trademark of Xerox Corp. 

3. System V is a trademark of AT&T. 
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□ STREAMS programming. This part describes the construction and 
installation of STREAMS drivers and modules, and provides pertinent 
reference material. 

□ Non-STREAMS appendices. The appendices summarize the available 
device driver routines, kernel support routines, and user support 
routines. One appendix contains sample driver listings. 

Light Blue Tabs. This manual is written for applications programmers writ¬ 
ing programs that run under SunView. SunView is an object-oriented sys¬ 
tem to support interactive, graphics-based applications running within win¬ 
dows. The manual assumes the reader understands C. SunView 1 Beginner’s 
Guide is a prerequisite. It complements the SunView System Programmer’s 
Guide described below. 

This manual is organized as a combination tutorial, user’s guide, and refer¬ 
ence manual. Chapters are devoted to operational concepts such as the Sun¬ 
View model, an overview of the user interface resources, using windows, 
handling input and the following objects in the interface toolkit: 

□ Windows, frames, canvases, Pixwins, text subwindows panels 

□ Menus, the notifier, cursor, icons. Alerts, TTY subwindows 

□ Scrollbars, the selection service, attribute utilities 

An interface elements summary is provided in one of the chapters. The ap¬ 
pendices provide example programs. Sun user interface conventions, and a 
reference section on converting SunWindows'’"''^ programs to SunView. 

Light Blue Tabs. This manual follows much of the structure and topics of 
the programmer’s guide described above, but from the point of view of how 
Sun View works on the inside, that is, the building blocks on which the ap¬ 
plication level is built and advanced application-related features. 

This manual is designed as a reference backup to the SunView 1 Program¬ 
mer’s Guide, which is a prerequisite. It provides a perspective and informa¬ 
tion on how to properly structure your applications so that lower-level de¬ 
tails are buffered from higher level layers. 

Chapters are devoted to the following topics: 

□ Windows, desktops, workstations, selection service and library 

□ Advanced notifier usages, menus and prompts 

□ User defaults database, advanced imaging, rects and rectlists 

Appendices provide a reference tutorial on writing a virtual user input de¬ 
vice driver and information on libraries, error messages, and debugging. 


SunView 1 System 
Programmer's Guide 


SunView 1 Programmer's 
Guide 
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Pixrect Reference Manual 


Pink Tabs. This manual describes the Pixrect graphics library, which is a 
set of routines that manipulate rectangular arrays of pixel values. These rou¬ 
tines, called RasterOps, are common to all Sun workstations. Application 
programs use these RasterOps to manipulate bit-mapped displays. 

The chapters of the manual describe the major features of the Pixrect li¬ 
brary: 

□ Portability, Pixrect operations 

□ Text facilities, Pixrect memory 

□ File I/O facilities 


Appendices describe writing a Pixrect driver, functions and macros, data 
structures, and curved shapes. 


Sun CGI Reference 
Manual 


SunCore Reference 
Manual 


Pink Tabs. SunCGI is an implementation of ANSI Computer Graphics In¬ 
terface (CGI). This manual is a user and reference manual for the applica¬ 
tions programmer of SunCGI applications. The manual assumes you are fa¬ 
miliar with interactive computer graphics and C. The chapters of the manual 
cover the following topics: 

□ Initializing and terminating 

□ Output, attributes, and input 

The appendices provide reference material, several example programs that 
can be used as templates for applications, guides for using SunCGI with Pix- 
wins and FORTRAN programs, and short C bindings. 

Pink Tabs. SunCore is an implementation of the ACM SIGGRAPH Core 
System. This manual is a user and reference manual for the applications pro¬ 
grammer of SunCGI applications. The manual assumes you are familiar 
with interactive computer graphics and C. 

The chapters of the manual cover the following topics: 

□ Program control 

□ Viewing operations and coordinate transforms 

□ Segmentation and naming 

□ Output primitives, attributes, and input primitives 

The appendices provide reference material, several example programs that 
can be used as templates for applications, and guides for using SunCore with 
Pascal and FORTRAN programs. 
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SPARC Documents 


SPARC Release Notes for 
4.0 


A RISC Tutorial, Sun 
Microsystems®, Inc. 


This chapter reviews the SPARC system software documentation set you re¬ 
ceive with your Sun computer system. Figure 6-1 illustrates the contents of 
the SPARC documentation box. The SPARC document set is written prima¬ 
rily for system and applications programmers who are engaged in develop¬ 
ing and porting applications to a SPARC system. 

The SPARC documents are: 

□ SPARC 4.0 Release Notes 

□ A RISC Tutorial 

□ Porting Software to SPARC Systems 

□ SPARC-4™ Assembly Language Reference Manual 

White Tab. The introduction of this manual summarizes the features of the 
32-bit SPARC architecture and the types of applications it supports. Chapter 
2 covers the features of the SPARC release such as: 

□ Changes to the system 

□ Running languages on the system 

□ Graphics enhancements 

□ SunView enhancements 

Other chapters are devoted to: 

□ PROM monitor commands 

□ Sun-4 Test System 

□ EEPROM layout 

An appendix provides an example configuration file. 

White Tab. This booklet talks about SPARC architecture under its impor¬ 
tant aspects of RISC architecture and open systems architecture. The book- 
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let introduces the basic concepts and describes the advantages and special 
implementations of SPARC architecture. 

Figure 6-1 SPARC Documents 



Porting Software to 
SPARC Systems 


SPARC-4 Assembly 
Language Reference 
Manual 


White Tab. This manual briefly describes the machine level SPARC archi¬ 
tecture, porting C, FORTRAN, and Pascal programs to a SPARC system. 
This manual and the following manual refer the reader to the SPARC Pro¬ 
cessor Architecture Manual (P/N 800-1399) for more information on 
SPARC machine-level architecture and the SPARC instruction set. 

White Tab. This manual briefly describes the SPARC assembler syntax, in¬ 
struction set mapping. It provides tables summarizing instruction set map¬ 
ping and pseudo-operations. An appendix describes the assembler com¬ 
mand and its operations. 
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Organizing Your 
Library of Sun 
System 

Documentation 


Figure 7-1 


Sun Binder Set 


Organizing and Researching Your 
Sun System Documents 

This chapter contains a sample plan for organizing your Sun software 
documents in binders and offers sample research and learning paths to 
follow some typical topics through your Sun software documentation. Plans 
are presented for learning about the following: 

□ Files 

□ SunOS commands 

□ Editing and formatting text 

□ System and network administration 

□ Application systems programming 

The best way to keep your Sun software documentation set may be to put 
the individual manuals into binders. There are two sizes of 3-ring binders 
that are particularly useful for this purpose. They are available from Sun. 
The binders have spine sleeves into which you can insert card stock labels 
naming the contents of the binders. The binders are silk-screened with a 
three-color design and the Sun logo. Figure 7-1 illustrates these two binders. 


Sun Binders 



A preplanned binder set is also available for the Sun-3'’'''^, Sun-4, and 
SPARC system documentation. It consists of 14 binders including four 1- 
inch, two 1-1/2-inch, and eight 2-inch binders. The binders include the ap¬ 
propriate spine labels. The order number of the set is BINDER-PKG-SS. 
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Table 7-1 shows an example of how one might organize the Sun manuals 
into these binders. This is only an example to get you started. Everyone will 
probably want their own arrangement. 

The table includes the reference manuals, the system and network adminis¬ 
tration manuals, and the programmer’s manuals. Since the manuals have 
initial manual title tabs, you can move the manuals around to find an ar¬ 
rangement that is most comfortable to you. 

Except for two, beginners guides are perfect bound and are 3-hole drilled. 
You can write or affix labels to the spines and place them on your bookshelf 
or place them in binders. The two that are pamphlet style, you can place in 
a 1-1/2-inch Sun binder. 
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Table 7 -1 Example Sun Library in Binders 


Size of Binder 

Title of Manual 

1-1/2-inch 

SPARCserver 390 Release Manual 

SunOS 4.0.3 Release Manual 

Installing the SunOS 4.0.3 

1-1/2-inch 

SunOS Change Notes 

Installing the SunOS 

2-1/2-inch 

System Services Overview 

System and Network Administration 

2-1/2-inch 

Security Features Guide 

Sun System Diagnostics Manual 

PROM User's Manual 

2-1/2-inch 

2-1/2-inch 
2-1/2-inch 

SunOS Reference Manual: 3 volumes 

Vol. 1 of 3: 1. User Commands 

Vol. 2 of 3: 2. System Calls, 3. Library Function, 4. Devices and Networking 

Vol. 3 of 3: 5. File Formats, 6. Games and Demos, 7. TROFF Macros and Misc. 
Tables, 8. Maintenance Commands 

2-1/2-inch 

Editing Text Files 

Using NROFF and TROFF 

Formatting Documents 

1-1/2-inch 

Global Index 

2-1/2-inch 

C Programmer’s Guide 

Assembly Language Reference Guide 

Debugging Tools 

Floating Point Programmer’s Guide 

2-1/2-inch 

Programming Utilities and Libraries 

1-1/2-inch 

Network Programming 

2-1/2-inch 

Writing Device Drivers 

2-1/2-inch 

SunView I Programmer’s Guide 

1-1/2-inch 

SunView 1 System Programmer’s Guide 

2-1/2-inch 

Pixrect Reference Manual 

Sun CGI Reference Manual 

SunCore Reference Manual 

1-1/2-inch 

SPARC 4.0 Release Notes 

A RISC Tutorial 

Porting Software to SPARC Systems 

SPARC-4 Assembly Language Reference Manual 
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Many subjects are covered in different manuals of the Sun software docu¬ 
mentation and to varying degrees of depth and detail. A complete course of 
study in a subject entails starting with the basics and progressing to more ad¬ 
vanced material. Therefore, a study and reading plan takes parts of or entire 
books from among the entire Sun documentation set and orders them in a 
progressive sequence. 

The following subsections are sample research and learning paths. You can 
make your own paths by looking up a subject in the Global Index and listing 
the entries in the order from most basic to more difficult. 

System and network administrators and programmers who are learning the 
SunOS system should not skip over the beginners guides. These guides pro¬ 
vide a good perspective and overview for anyone who is introducing them¬ 
selves to the Sun system environment. 

The plans are arranged as a tables with entries broken down to the chapter 
and manual title. Entries are in the order recommended for reading. 

Since SunOS (and UNIX) are file-oriented operating systems, one might be¬ 
gin with a plan for learning about the SunOS file system and file manipula¬ 
tion. 


Table 7-2 Study Plan for Learning About Files 


Book Title 

Chapter 

Sun System Introduction 

Getting Started with SunOS 

Getting Started with SunOS 

Doing More with SunOS 

Doing More with SunOS 

SunOS Reference Manual 

SunOS Reference Manual 

Ch. 7 Working With Files 

Ch. 4 Files and the File System 

Ch. 8 Searching Through Files 

Ch. 2. More About Files 

Ch. 6 Managing Your Files 

Sec. 7 Public Files, Tables, and TROFF Macros 

Sec. 5 File Formats 


Learning about 
Specific Subjects 


Learning About Files 
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Learning to Use SunOS study and reading plan lists the books and chapters covering SunOS 

Commands commands. 


Table 7-3 Study Plan for Learning SunOS Commands 


Book Title 

Chapter 

Sun System Introduction 

Ch. 5 Using Shells 

Sun System Introduction 

Ch. 6 User Access and Commands 

Getting Started with SunOS 

Ch. 5 Commands 

Getting Started with SunOS 

Ch. 9 Timesaving Features 

Getting Started with SunOS 

Ap. A Command Summary 

Using the Network 

Ch. 2 Login Access to Other Machines 

Using the Network 

Ch. 3 Mounting Remote File Systems 

Using the Network 

Ch. 4 Issuing Commands to Remote Machines 

Using the Network 

Ap. A Command Summary 

Doing More with SunOS 

(all chapters and appendices) 

Getting Started with SunOS 

Ch. 10 OnLine Documentation 

SunOS Reference Manual 

(all sections) 


Learning to Edit and xhis study and reading plan lists the books and chapters covering editing 

Format Text and formatting text especially aimed at the use of TROFF. 


Table 7-4 Study Plan For Editing and Formatting Text 


Book Title 

Chapter 

Sun System Introduction 

Ch. 8 Editing Text Files 

Sun System Introduction 

Ch. 9 Formatting Documents 

Getting Started with SunOS 

Ch. 6 Editing Files 

Getting Started with SunOS 

Ch. 7 Formatting Files 

SunView 1 Beginner’s Guide 

Ch. 1 Using the Text Editor 

SunView I Beginner’s Guide 

Ch.Il All About Tools 

Doing More with SunOS: Beginner’s G. 

Ch. 7 More About Printing (Files) 

Editing Text Files 

(Reference Manual) 

Using NROFF and TROFF 

(Reference Manual) 

Formatting Documents 

(Reference Manual) 

SunOS Reference Manual 

Sec. 7 Public Files, Tables, and TROFF Macros 
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Learning System and 
Network Administration 


This study and reading plan lists the books and chapters covering the duties 
of a system and network administrator. 


Table 7-5 Study Plan For a System and Network Administrators 


Book Title 

Chapter 

Sun System Introduction: Beginner’s G. 

Ch. 11 SunOS Internal Features 

Sun System Introduction: Beginner’s G. 

Ch. 12 System Administration 

Setting Up Your SunOS Environment 

(all chapters) 

SunView 1: Beginner’s Guide 

Ch. 10 Using the Defaults Editor 

Self Help with Problems: Beginner’s G. 

(all chapters) 

Using the Network: Beginner’s Guide 

(all chapters) 

Mail and Messages: Beginner’s Guide 

(all chapters) 

System Services Overview 

(all chapters) 

System and Network Administration 

(all chapters) 

Security Features Guide 

(all chapters) 

SunOS Reference Manual 

Sec. 8 Maintenance Commands 

Sun Systems Diagnostics Manual 

(all chapters) 

PROM User’s Manual 

(all chapters) 

Installing the SunOS 

(all chapters) 


Learning the SunOS 
System for Programmers 


This study and reading plan lists the books and chapters introducing the Sun 
programming environment to application systems programmers. 


Table 7-6 Study Plan For Application System Programmers 


Book Title 


Chapter 


Sun System Introduction: Beginner’s G. 
Sun System Introduction: Beginner’s G. 
Doing More with SunOS: Beginner’s G. 
Doing More with SunOS 
Sun System Introduction: Beginner’s G. 
Sun System Introduction: Beginner’s G. 
Sun System Introduction: Beginner’s G. 
System Services Overview 
SunOS Reference Manual 
Programming Utilities and Libraries 
Programmer’s manuals 


Ch.Il SunOS Internal Features 

Ch 5 Using the Shells 

Ch. 4 The C Shell 

Ch. 6 Managing Your Files 

Ch. 13 Software Development 

Ch. 14 Graphics Software 

Ch. 15 Unbundled and Third Software 

(all chapters) 

(applicable chapters) 

(all chapters) 

(applicable manuals) 
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Alphabetic Document Descriptions 


This appendix contains a table listing the software documents you receive 
with your Sun computer system. The entries are arranged alphabetically for 
your convenience. The last column of the table refers to the chapter of this 
booklet in which the manual is described. The table does not include RTFs. 
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Table A-1 Alphabetic List of Sun System Software Documents 


Title 

Chapter 

Assembly Language Reference for Sun-2 and Sun-3 

5 

The C Programming Language 

5 

C Programmer’s Guide 

5 

Debugging Tools 

5 

Doing More with SunOS: Beginner’s Guide 

2 

Editing Text Files 

3 

Floating Point Programmer’s Guide 

5 

Formatting Documents 

3 

Getting Started with SunOS: Beginner’s Guide 

2 

Global Index 

1,3 

Installing the SunOS 

4 

Mail and Messages: Beginner’s Guide 

2 

Network Programming 

5 

Pixrect R^erence Manual 

5 

Porting Software to SPARC Systems 

6 

Programming Utilities and Libraries 

5 

PROM User’s Manual 

6 

A RISC Tutorial 

6 

Security Features Guide 

4 

Self Help With Problems: Beginner’s Guide 

2 

Setting Up Your SunOS Environment: Beginner’s Guide 

2 

SPARC Architecture Manual 

6 

SPARC Release Notes 

6 

Sun-4 Assembly Language Assembly Language Reference Manual 

5 

Sun System Diagnostics Manual 

4 

Sun System Introduction: Beginner’s Guide 

2 

SunCGI Reference Manual 

5 

SunCore Reference Manual 

5 

SunDiag User’s Guide 

4 

SunOS Reference Manual 

3 

SunOS 4.0 Change Notes 

4 

SunView I: Beginner’s Guide 

2 

SunView I Programmer’s Guide 

2 
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Table A-2 Alphabetic List of Sun System Software Documents (continued) 


Title 

Chapter 

SunView I System Programmer’s Guide 

5 

System and Network Administration 

4 

System Services Overview 

4 

Using NROFF and TROFF 

3 

Using the Network: Beginner’s Guide 

2 

Writing Device Drivers 

5 
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READER COMMENT SHEET 


Dear Reader, 

We who work at Sun Microsystems wish to provide the best possible documentation for our products. To this 
end, we solicit your comments on the Guide to Sun System Software Documentaion, Part Number 800-3855. 
We would appreciate your telling us about errors in the content of the manual, and about any material that you 
feel should be there but isn’t. 


Typographical Errors 

Please list typographical errors by page number and actual text of the error. 


Technical Errors 

Please list errors in technical accuracy by page number and actual text of the error. 
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Content 

Did this guide meet your needs? If not, please indicate what you think should be added or deleted in order to 
do so. Please comment on any material that you feel should be present but is not. Is there material found in 
other manuals that would be more convenient if it were in this manual? 


Layout and Style 

Did you find the organization of this guide useful? If not, how would you rearrange things? Do you find the 
style of this manual pleasing or irritating? What would you like to see different? 


Mail this completed form to: 

Manager, Hardware Technical Publications 
Sun Microsystems, Inc. 

2550 Garcia Avenue 
Mountain View, CA 94043 
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